/**
 * 项目名：	Rumba Plan
 * 
 * 版权所有(C)，上海海鼎信息工程股份有限公司，2006，所有权利保留。
 * 
 * 文件名：	IBCartridgeMgr.java
 * 模块说明：	
 * 修改历史：
 * 2006-10-25 - lxm - 创建。
 */
package com.hd123.rumba.cartridge.biz;

import java.util.List;

import net.sf.hibernate.HibernateException;

import org.w3c.dom.Document;
import org.w3c.dom.Element;

import com.hd123.rumba.cartridge.entry.Entry;
import com.hd123.rumba.exception.BusinessException;
import com.hd123.rumba.runtime.biz.IBManager;
import com.hd123.rumba.util.Version;

/**
 * 构件包 | 业务层 | 管理员 | 接口类
 * 
 * @author lxm
 * 
 */
public interface IBCartridgeMgr extends IBManager {

  // /**
  // * 初始化构件包。提供给系统在初始化时调用。<br>
  // * 检查并将构件包数据写入数据库。
  // *
  // * @param cartUuids
  // * 指定需要初始化的构件包uuid列表。
  // * @throws BusinessException
  // * @throws HibernateException
  // * @deprecated
  // */
  // public void initCartridgesT(List<String> cartUuids) throws Exception;

  /**
   * 注册构件包到内存注册表。<br>
   * 提供给引导程序使用。
   * 
   * @param cartUuids
   *          指定装载的构件包uuid列表。
   * @throws BusinessException
   */
  public void registerCartridges(List<String> cartUuids) throws BusinessException;

  /**
   * 验证所有注册表中的构件包是否被正确安装。<br>
   * 包括对版本号的检查。
   * 
   * @throws BusinessException
   * @throws HibernateException
   */
  public void verifyCartridges() throws BusinessException, HibernateException;

  /**
   * 取得指定构件包目前数据库的版本号。<br>
   * 本过程不会提交数据库错误，若处理过程中发生数据库错误，比如数据表不存在，则直接返回“0.0.0.0”。
   * 
   * @param cartUuid
   *          指定的构件包的uuid。
   * @return 返回版本号。
   * @throws BusinessException
   */
  public Version getDBVersion(String cartUuid) throws BusinessException;

  /**
   * 开始升级处理。<br>
   * 将在数据库中设置正在升级的标记。对应{@link #endUpgradeT()}可以消除这个升级标记。<br>
   * 若指定的构件包尚未被新增保存到数据库中，该方法将不做任何事，但方法调用仍然成功。
   * 
   * @param cartUuid
   *          指定当前升级构件包的uuid。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void beginUpgradeT(String cartUuid) throws BusinessException, HibernateException;

  /**
   * 结束升级处理。<br>
   * 修改数据库版本号，并标记数据库升级结束。<br>
   * 若不存在相应的构件包记录，将自动新增。
   * 
   * @param cartUuid
   *          指定的构件包的uuid。
   * @param version
   *          指定目标版本号。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void endUpgradeT(String cartUuid, Version version) throws BusinessException,
      HibernateException;

  /**
   * 保存构件包，专供安装构件包时使用。<br>
   * 本方法设计为编写构件包的安装程序的时候使用。<br>
   * 一个典型的安装过程应该开始于{@link #beginUpgradeT}，结束与{@link #updateDBVersion}，也就是说设计者认为
   * 只应在这两个函数之间被调用。<br>
   * 本方法其中只对构件包进行新增保存，若数据库中已经存在该数据，则不做任何事情。
   * 
   * @param cartUuid
   *          指定被保存的构件包uuid。
   * @param version
   *          指定构件包当函数被调用时的版本号。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void saveCartridgeForInstallT(String cartUuid, Version version) throws BusinessException,
      HibernateException;

  /**
   * 取得当前系统已经安装的全部构件包。
   * 
   * @return 构件包列表。
   * @throws BusinessException
   */
  public List<BCartridge> getAllCartridges() throws BusinessException;

  /**
   * 根据uuid取得构件包对象。
   * 
   * @param uuid
   *          指定构件包的uuid。
   * @return 返回取得的构件包对象，若找不到返回null。
   * @throws BusinessException
   */
  public BCartridge getCartridge(String uuid) throws BusinessException;

  /**
   * 根据前缀取得构件包对象。
   * 
   * @param prefix
   *          指定构件包的前缀。
   * @return 返回取得的构件包对象，若找不到返回null。
   * @throws BusinessException
   */
  public BCartridge getCartridgeByPrefix(String prefix) throws BusinessException;

  /**
   * 根据uuid取得构件包功能视图对象。
   * 
   * @param uuid
   *          指定构件包功能视图的uuid。
   * @return 返回取得的构件包功能视图对象，若找不到返回null。
   * @throws BusinessException
   */
  public BCartFunctionView getFunctionView(String uuid) throws BusinessException;

  /**
   * 取得系统定义的所有构件包功能视图对象列表。
   * 
   * @return 功能视图列表
   * @throws BusinessException
   */
  public List<BCartFunctionView> getAllFunctionViews() throws BusinessException;

  /**
   * 根据前缀取得构件包功能视图对象。
   * 
   * @param prefix
   *          指定构件包功能视图的前缀。
   * @return 返回取得的构件包功能视图对象，若找不到返回null。
   * @throws BusinessException
   */
  public BCartFunctionView getFunctionViewByPrefix(String prefix) throws BusinessException;

  /**
   * 取得依赖于指定的构件包功能视图的所有构件包功能视图。
   * 
   * @param referredCFVUuid
   *          指定被依赖的构件包功能视图uuid。
   * @return 返回符合条件的构件包功能视图列表。
   * @throws BusinessException
   */
  public List<BCartFunctionView> getReferringCFVs(String referredCFVUuid) throws BusinessException;

  /**
   * 根据构件包功能视图和唯一标识查找模块功能入口。
   * 
   * @param cfvClass
   *          指定构件包功能视图。
   * @param id
   *          指定模块功能入口的id。
   * @return 返回找到的模块功能入口对象，若找不到则返回null。
   * @throws BusinessException
   */
  public Entry getEntryById(Class cfvClass, String id) throws BusinessException;

  /**
   * 取得制定构件包对应的配置文件的XML DOM文档。
   * 
   * @param <T>
   * @param cart
   *          指定的构件包的类。
   * @return 返回取得的配置文件，为XML DOM Document对象。若找不到则返回null。
   * @throws BusinessException
   */
  public <T extends BCartridge> Document getCartridgeConfigDocument(Class<T> cart)
      throws BusinessException;

  /**
   * 根据配置文件初始化构件包。即从配置文件中读取并写入到构件包中，作为初始化属性。
   * 
   * @param cart
   *          指定的构件包对象。
   * @param doc
   *          指定的配置文件，是一个XML Document。
   * @throws BusinessException
   */
  public void initCartridgeByConfig(BCartridge cart, Document doc) throws BusinessException;

  /**
   * 根据配置文件初始化构件包功能视图。即从配置文件中读取并写入到构件包功能视图中，作为初始化属性。
   * 
   * @param cfv
   *          指定的构件包功能视图对象。
   * @param e
   *          指定包含配置信息XML DOM Element。
   * @throws BusinessException
   */
  public void initCFVByConfig(BCartFunctionView cfv, Element e) throws BusinessException;
}
